The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / c / sozobon / sozbin15.zoo / sozdistr / doc / binary.doc / cc.man < prev next >

Wrap

Text File | 1995-10-01 | 19.6 KB | 503 lines

CC(1) USER COMMANDS CC(1) NAME cc - Sozobon C Compiler Driver (eXtended version) SYNOPSIS cc [options] files cc [-h][-cOSPEvVnpgft]]+P] [-o <file> ][-W<n> ][-{T|s} <file> ] [-L<path> ][-I<path> ][-D<sym> ][-U<sym> ][-X[n][func] ][-F <file> ] [-W<any_text> ][-mshort ][-mlong ][-e[fs] ][-u <sym> ][-l <name> ] [--version ][--help ][--nostdlibs ][--sdir <path> ][--odir <path> ] [--mint ][--c68 ][--dlibs ][--stdbinaries ][--libc <file> ][--size-t-long] [+P<opstr> ][+C<opstr> ][+O<opstr> ][+A<opstr> ][+L<opstr> ] [<file>] [<file> ...] DESCRIPTION This eXtended version of Sozobon compiler driver uses a command syntax like that of a many "C" compilers. The cc command runs the passes of the compiler as needed to process files given on the command line. Various options exist to control the execution of cc or the compiler passes it runs. When you invoke cc, it normally does compilation, assembly and linking, but not preprocessing. Sozobon has an internal preprocessor. Filenames which end in '.c' are taken as "C" source to be compiled or preprocessed; filenames ending in .i are taken as preprocessor output to be compiled; compiler output files and any input files with names ending in .s are assembled; then the resulting object files, and any other input files, are linked together to produce an executable. Command line options allow you to stop this process at any intermediate stage. cc recognizes file names with the following extensions: .c C Source File .i Preprocessor Output File (made from C source file) .tmp Assembly Language Input For Optimizer .cpp Assembly Language Input For Preprocessor .spp Assembly Language Input For Preprocessor .s Assembly Language Input For Assembler .o Relocatable Object Module .a Library Module .lib Library Module If a filename has no extension, it is assumed to be a library or object module. The name of the executable is based on the first file name on the command line. If the first filename was "foobar.c", the resulting executable would be named "foobar.out". When a file generated during a compilation pass is no longer needed (the next level of output has been generated from it) then it is deleted. Only '.o' and executables are exempt from this; they are deleted only if the compilation pass that generates them fails. If an executable is created in one compilation pass, however, the '.o' file will be deleted (since it is not needed). There are many options that allow you to control cc, and there are other options available to allow other compiler tools to be controlled. Cause the hcc's commanline syntax changed a little bit you can use this cc now for Thorsten Roskowetz's port of the c68 compiler, too. OPTIONS The first options to be discussed will be the options that control the overall compilation process. -c Compile or assemble the source files, but do not link them. Object files produced by this option will be named exactly like the source files from which they were generated, but with a '.o' extension instead of a '.s' or '.c' extension. Object files specified as input will be ignored. -O Execute the assembly optimizer between the compiler stage and the assembler stage. The '.s' files generated during the compiler stage will be renamed to '.tmp' files, and new (optimized) '.s' files will be created. -S Compile the source files, but do not assemble them. The assembler files produced by this option will be named exactly like the source files from which they were generated, but with a '.s' extension instead of a '.c' extension. Object files and assembler source files specified as input will be ignored. If specified, the assembly optimizer will be executed. If cc is invoked with the '-c' option following this option, an executable will be created, but the '.s' files and '.tmp' files will not be deleted. -P Execute the "C" preprocessor only. All specified source files will be preprocessed. The output files produced by this option will be given a '.i' extension. Since Sozobon "C" has no stand-alone 'cpp', this option is provided for compatability and to enable the easy generation of preprocessed '.c' files as input for other tools. -E Same as -P, but output of ccp goes to stdout. +P Run the preprocessor on c files first. This is useful if there are preprocessor statements hcc doesn't know in the source, or you make use of another compiler with $CC1 variable. machine dependency options (-m...) -mshort Does actually nothing cause short int is default in SOZOBONX -mlong Ints are 32 Bit values (longs), this is passed to hcc, and special libraries - which don't exist yet - get linked (<lib>32) The following switches control cc itself, the output files, and the linker: -v The compiler driver program will display the commands it executes as it performs preprocessing, compilation, assembling, and linking. -V Same as above, but the verbose option is also given to each tool. -h This switch will cause a help page to be displayed. -n This option (which is verbose) will show you how cc would react to the command line given. It will also create a link file, so that you can see what would be done with a special command line you typed. No actual work is done, though. This is not standard, so this switch may change in future. -o <file> This option (passed to the linker) specifies to which file ld output will be written. By default, ld output is written to a file with the same filename as the first input filename, but with a '.out' extension. If there is no input filename (-F) then the output will be written to a file called 'a.out'. When used with the options '-c' or '-S', 'file' is taken as the name of the assembler output file. -g This option is passed to assembler and linker, so that all symbols will be kept in the outputfiles. The optimizer is told not to produce code, that may confuse a debugger. -p This option enables runtime execution profiling. It is passed to the compiler as '-P', and forces the linker to use a different startup code and a special runtime library. -f This option tells ld to use a library including some floating point functions 'libc.a' and not the integer only lib 'libci.a'. If there is no 'libci.a' in the selected library directory 'libc.a' is used always. With the math library option '-lm' specified you won't need an extra '-f' option. -X[<n>][<function>] This option forces the compiler and the "C" preprocessor to generate debug code. The optional <function> is only valid for hcc. The way the debug code works is of course compiler dependant, and will (still) differ for cpp and hcc. This option tells the linker to make use of a special catch exceptions library 'except.a'. handling of error mesages (-e...) -e Every program called by cc is forced to write error messages to a file having the name of the program, with a '.err' extension. Before every execution, the error file is removed so that it will always contain the correct information. You will be warned by cc if the error file is not empty after an execution. If the error file is empty, it is simply deleted. -ef This switch is the same as the '-e' switch, but the error file is given the same filename as the source file, with a '.x_e' extension, where 'x' is the one letter extension of the source file. For example, hcc would write error messages to 'foobar.c_e', and jas would write error messages to 'foobar.s_e'. -es This switch is the same as the '-e' switch, but the error files are "saved" (copied to the files 'compile.err', 'assemble.err', and 'link.err'. There will soon be an options (-ec) that will gather all error files into a file called 'compiler.err'. -B<binaryprefix> The string <binaryprefix> and the binary name are concatenated before cc tries to find and call the binary. some options for the linker pass -F <file> By default, cc creates a link file to tell ld which files to link. This file is written to '$TMPDIR\ldfile.tmp' and removed if the linker was successfull. It contains libraries and objects according to the information found on the command line. If you want to control what the linker will link together, you can write a linkfile and force it to be used using the -F option. -T <file> -s <file> This switch allows you to specify a startup module to be used instead of the default startup module. Various options (-p, -X, -f) cause different startup modules to be used. -l <name> Add library 'lib<name>.a' and '<name>.a to linking list. --libc <file> This switch is similiar to the '-s' switch, but it affects which standard library is used. -L<path> This switch will cause <path> to be added to the search list for libraries. -t This switch will cause the linker to generate a symbol table. +L-p This switch will cause the linker to rescan the libraries for unsatisfied external declarations. Some multiletter options are to prefix by '--': --stdbinaries The deafult builtin binary names or the ones from the environment are replaced by the default C compiler system names: cc1, as, opt and ld. The calling conventions follow the deafult modes, too: 'cc1 <options> infile outfile', etc... --nostdlibs This switch inhibits the use of any standard library files (or startup modules), except those specified with the '-s' and '-l' switches. Nothing not on the command line will be linked. --sdir <path> This switch causes the generated assembler files and all following files are written to the <path> directory. --odir <path> This switch causes the generated object code files to be written to the <path> directory. --mint --MiNT The startup code and libraries to link are the MiNT libs: (crt0.o, libc.a from directory 'mntlib') --size-t-long cc uses HCC and standard libraries for sizeof() type 'unsigned long'. library names look like <standard-name>t.a --c68 cc is switched to 'c68' mode, which is another compiler you can use with the SozobonX distribution. 'cpp' is always used in this mode, the compiler binary is assumed as 'c68.ttp', the libraries are searched in SozobonX's 'c68' library directory. The header files default to be the MiNT lib ones cause it's a Mint lib. To make use of 'c68' slightely better error messages, warnings and prototype tests for function arguments you may want to run it on all your sources. So a commandline like 'cc --c68 --xdlibs +C-nocode <file>' will produce what you expect. --dlibs --DLibs The startup code and libraries to link are the original DLibs: (libc.a and crt0.o from directory 'dlibs') Some options (which are not of interest in cc) are passed directly to the tools executed by cc. The following options are passed to the preprocessor and the compiler: -I<path> Add directory <path> to the header search list. -D<sym> Define the preprocessor symbol 'sym' as 1. -D<sym=val> Define the preprocessor symbol 'sym' as 'val'. -U<sym> Undefine the built-in symbol 'sym'. -W<n> With this option set, the compiler is told to stop compiling after n error messages or warnings. -W<any_text> This argument is passed to preprocessor and compiler without any changes. It is used to switch on/off warning messages. The following option is passed to the linker: -u <sym> This switch tells ld to undefine the symbol <sym>, so it is linked from the library. The following options allow you to pass commands directly to the various compiler tools. These options are prefixed with a '+' sign. They may contain any characters, but no whitespace. You can, of course, pass more than one options string to a compiler tool using the '+?' option. +P<optstring> The string <optstring> is passed to cpp. Example: '+P-C' will force cpp to write all comments to an ouput file. cpp will get this as '-C' in the command line. +C<optstring> The string <optstring> is passed to hcc. +O<optstring> The string <optstring> is passed to top. +A<optstring> The string <optstring> is passed to jas. +L<optstring> The string <optstring> is passed to ld. ENVIRONMENT cc assumes that it will find files in the paths declared in the following environment variables. Some locations are predefined with annotated definitions: $PATH \bin,\sozobon\bin (path of executables) variable replaces builtin ones $LIBDIR \usr\lib (standard library path) This variable replaces builtin one. cc expects to find in this directory the 'sozobox' directory with the different library directories to select with --mint option for example. $LIB If this variable exists The libraries and object modules are searched here and in cwd. $LIBDIR is ignored. $INCLDUEDIR '\usr\include' cc wil construct the $INLCLUDE variable using this path and the options like --mint. It is expected to keep the include directories for the different libraries there (xdlibs, mntinc, dlibs) $INCLUDE With this variable existing no new $INCLDUE is built by cc. $TMPDIR .\ $SOZLIBS A list of additional libraries and objects to the standard libraries and objects to find in $LIBDIR or with $LIB $SOZBIN (path of executables) Each directory should be separated by a ',' or ';'. The current directory is always searched first. $LIBDIR is the path of /usr/lib in standard filesystems. cc will try to find a directory called 'sozobonx' there, because $LIBDIR i.e. "\usr\lib" is used by other programs too. This is the place for standard libraries: \usr\lib\sozobonx any common libraries here \usr\lib\sozobonx\xdlibs \usr\lib\sozobonx\mntlib \usr\lib\sozobonx\dlibs In your shell: export LIBDIR=\\usr\\lib or in the makefile or your shell: LIB=\usr\otherlib,anypath\anylib All files will be searched only in $LIB and '-L' argument pathes, if specified, and in e.g. in: $LIBDIR\sozobonx\xdlibs,$LIBDIR\sozobonx if $LIB isn't specified. $TMPDIR is only used for the linkfile. If not set the current directory is used. $SOZLIBS may contain a list of libraries (and object files) to use as additional standard libraries. This feature/variable was added for all those who do not use make, where you can specify a variable $(LIBS) or $(LOADLIBES) which does the same. Example: setenv SOZLIBS "aesfast,vdifast" The files from $SOZLIB are ignored with the --nostdlibs switch, too. $SOZBIN may contain a single path or a list of directories, in which the executables (hcc, top, jas, ld) will be found. You need not set this environment variable if the excutables are found in the $PATH environment variable. If you keep your Sozobon binaries in a special directory, though, you should set this environment variable. It is used instead of $PATH if set; the default location is only used if $PATH is not set! Some environment variables may contain the names of the binaries to execute, and the standard library - if not the default ones should get used (just export the variables in the makefile): $CPP cpp Preprocessor $CC1 hcc Compiler $OPT top Optimizer $AS jas Assembler $LD ld Linker $CRT0 crt0.o Startup Code $LIBC libc[32].a standard runtime library If $STDERR ist set all output will go to filehandle 2, if not and cc isn't called with ARGV method all this is printed to 'CON:', filehandle -1. FILES Libraries: Startup Codes crt0.o pcrt0.o (normal, -p option) catch exceptions library except.a (with -X option) Standard Runtime Library (suffix .a) libc libcp (with -p option) math library (with -f option) libm libmp (with -p options) With the -mlong option the string "32" is added to the above filename (e.g.: libc32) These libraries are searched in the library directory 'sozobonx'. There are different directories expected (xdlibs, mntlib dlibs), all containing the above files. Which one is used, depends on different cc options: --xdlibs(default) --mint --dlibs Filename Extensions: .app, .ttp, .prg, .tos, .gtp, .c, .i, .tmp, .cpp, .spp, .s, .o, .a, .lib Filenames: $TMPDIR\ldfile.tmp Linkfile (generated) The order in the linkfile is: 1) The startup module. 2) The specified input files (same order as on the command line). 3) The files from $SOZLIB (same order). 4) The built-in standard libraries. FILE.c Source Code Generated Files: cpp: FILE.c -> FILE.i FILE.cpp -> FILE.s FILE.spp -> FILE.s hcc: FILE.c -> FILE.s top: FILE.tmp -> FILE.s (during a pass FILE.s is first moved to FILE.tmp, so FILE.s is always the valid assembly language file) jas: FILE.s -> FILE.o ld: a.out Linker Output (generated) FILE may contain path specifications, but $CWD is always assumed. LIMITS Maximum libraries from environment variable $STDLIBS: 30 COPYING This is cc 2.04, an eXtended version, May 94 by Jerry G. Geiger. I modified version 1.01, Copyright (c)1988 by Sozobon, Limited, to produce this compiler, to work with eXended versions of Sozobon C by Holger Weets, Christian Wempe und Frank Specht. BUGS No doubt, there are some bugs. If you find one, please report it to me: Maus: Jerry Geiger @B Internet: jerry@zedat.fu-berlin.de SEE ALSO make(1), cpp(1), hcc(1), top(1), jas(1), ld(1).